Adds pull request template #3943

KOTungseth · 2025-11-14T18:28:15Z

Summary

Introduces a new pull request template for the Elastic Docs repository that includes required GenAI disclosure questions. The template is designed to help internal and external contributors provide clear and accurate documentation updates while ensuring transparency around AI-assisted contributions.

What’s changing

Adds a new PR template to .github/PULL_REQUEST_TEMPLATE.md.
Incorporates two GenAI disclosure questions drafted by Legal:
- Whether a GenAI tool was used.
- Which tool(s) and model(s) were used, if applicable.

Why this change is needed

The Elastic Legal and Open Source teams have requested that all public-facing repositories include standardized questions about generative AI usage in documentation contributions. These questions help us:

Maintain transparency regarding AI-assisted content.
Support responsible and high-quality use of AI for documentation.
Ensure reviewers have the context needed to evaluate contributions.
Establish consistency across Elastic open repositories, particularly as external contributors begin using AI more frequently.

Adding this template to the Elastic Docs repo also helps contributors understand our expectations upfront and aligns with the AI & Docs Guidelines we’ve developed internally.

What's needed from reviewers

Content accuracy and clarity: Does the wording in the template feel clear, welcoming, and consistent with our documentation standards?
Completeness: Are there additional checklist items or guidance we should add for contributors?

Additional question

Should we also include a separate template specifically for external contributors, or is the single unified template sufficient?

bmorelli25 · 2025-11-14T18:43:27Z

Thanks for doing this. The things that are most important to me in a PR description are:

Links to related issues
Explanation of the change
Explanation of the rationale behind the change
Exactly what you need from reviewers. Who do you need a review from and what should they check/verify/decide/answer? Are there specific questions you want answered? Sections that should be looked at more deeply than others?

The AI stuff makes sense too.

If we're going to include a checklist, I think it should include testing the changes and/or validating against the UI. And ensuring folks are writing cumulative docs. But it's a bit of a slippery slope from there. Was the code validated? Were the snippets tested? Did you explore other areas where this content could live? Were all instances updated?

Copilot

Pull Request Overview

This PR introduces a standardized pull request template for the Elastic Docs repository to streamline the contribution process and ensure consistency across submissions.

Adds a structured PR template with Summary and Checklist sections to guide contributors
Includes a Generative AI disclosure section to track usage of AI tools in contributions
Provides a link to contribution guidelines for additional reference

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

bmorelli25 · 2025-11-14T19:44:46Z

Top PR Review Issues - Quick Reference

Quick scan of the most common issues found in PR reviews. Based on analysis of 300 recent PRs with 1,547 review comments (including 585 suggestion blocks).

This comment was generated by Claude. Maybe it's helpful for determining what folks are generally missing or forgetting about in their PRs?

Top Issues by Frequency

Links and References (79 PRs, 294 comments) - Broken internal/external links, incorrect link anchors, wrong relative paths, links pointing to non-existent content, missing links
Content Structure and Organization (70 PRs, 147 comments) - Sections in wrong order, headings that don't accurately describe content, poor paragraph structure, related content not grouped together, tutorial steps not properly structured
Content Improvements (58 PRs, 445 comments) - General content suggestions, additions, removals, rewrites, and improvements suggested by reviewers
Technical Accuracy (53 PRs, 91 comments) - Code examples that don't work, incorrect version numbers or compatibility info, invalid configuration examples, outdated information
Markdown Formatting Issues (49 PRs, 137 comments) - Indentation and whitespace inconsistencies, missing backticks for inline code, improper markdown syntax, missing language tags in code blocks, inconsistent list formatting, incorrect heading hierarchy
Attributes and Variables (46 PRs, 94 comments) - Hardcoded product names instead of attributes ({{es}}, {{kib}}, {{esql}}), incorrect attribute syntax, abbreviations not using available attributes
Context and Completeness (40 PRs, 60 comments) - Missing background information, lack of context, missing links to related documentation, prerequisites not mentioned, unclear explanations
Applies_to Metadata / Cumulative Docs (33 PRs, 58 comments) - Missing or incorrect applies_to tags, incorrect syntax for applies_to badges, not using applies_to when content is version-specific or deployment-specific, not following cumulative docs guidelines, incorrect version ordering in cumulative content
Clarity and Precision (26 PRs, 31 comments) - Unclear or ambiguous language, unnecessary words, technical terms not explained, instructions not actionable
Preview and Testing (24 PRs, 35 comments) - Changes not previewed before submission, code examples not tested, formatting not verified in rendered output
Images and Media (20 PRs, 40 comments) - Missing alt text, incorrect image file paths, file names don't follow conventions, images not optimized, inaccurate captions
Terminology and Consistency (16 PRs, 19 comments) - Inconsistent terminology, capitalization doesn't match style guide, inconsistent use of abbreviations, naming conventions
Spelling and Grammar (10 PRs, 13 comments) - Typos and misspellings, incorrect capitalization, punctuation errors, inconsistent terminology
Snippets and Includes (8 PRs, 13 comments) - Duplicating content instead of using snippets, incorrect snippet paths, referenced snippets don't exist
Frontmatter and Metadata (5 PRs, 5 comments) - Incorrect frontmatter YAML, missing required metadata fields, inaccurate title or description
Quality Checks (2 PRs, 3 comments - but highly recommended) - Acrolinx quality checks not run, Vale rule violations not fixed, linter warnings ignored

bmorelli25 · 2025-11-20T00:10:19Z

.github/PULL_REQUEST_TEMPLATE.md

+Describe what your PR changes or improves.  
+Describe the reason you are making this change. 
+If your PR fixes an issue, link it here.


I would make all of the instructions comments. Otherwise people will forget and we'll have super long PR descriptions of mostly instructions.

Suggested change

Describe what your PR changes or improves.

Describe the reason you are making this change.

If your PR fixes an issue, link it here.

I also like thinking about: What problem does it solve? Any tradeoffs?

Describe the reason you are making this change.

This IMO should come from the issue and shouldn't need repeating.
What is most important here is the implementation detail (what the changes are, and optionally how do these changes solve the issue if not already captured in the issue)

I combined the summary section so it now appears as:

Describe what your PR changes or improves.
If your PR fixes an issue, link it here. If not, describe the reason you are making the change.

Love the idea to turn all the instructions into comments.

.github/PULL_REQUEST_TEMPLATE.md

bmorelli25 · 2025-11-20T00:12:01Z

.github/PULL_REQUEST_TEMPLATE.md

+2. If you answered "Yes" to the previous question, please specify the tool(s) and model(s) used (e.g., Google Gemini, OpenAI ChatGPT-4, etc.).
+
+Tool(s) and model(s) used:


Same here. I'd comment out the instructions if we can.

Suggested change

2. If you answered "Yes" to the previous question, please specify the tool(s) and model(s) used (e.g., Google Gemini, OpenAI ChatGPT-4, etc.).

Tool(s) and model(s) used:



Tool(s) and model(s) used:

I'm not really sure if there's much point in specifying what model or tool one used TBH, the point is signaling what information the author isn't confident about because they relied on AI to generate it

We need to know where the data might have been ingested / processed.

I understand, just not sure if a PR template is the right place for this. I think you're getting at the fact that non-public information shouldn't be used with these tools, but it's too late if the PR is already up.

Shouldn't we have rules against using certain tools if that's the case, rather than asking for information after the fact? I'm just trying to get at the real point of this.

What we aim to avoid is merging code / docs that might have been processed from models we haven't approved — in this case, the PR gate provides a measure of liability / transparency / honesty.

The more I think about this, the more I think we should just bake this into our CLA 😄

I'll touch base with Legal about including this in our CLA, but in the meantime, this is the verbiage Legal is going forward with to meet our policy standards.

bmorelli25 · 2025-11-20T00:17:40Z

.github/PULL_REQUEST_TEMPLATE.md

+
+--
+
+## Reviewers and timeline


The table feels overly complex. I also don't really understand the review timelines still. More useful IMO is the PR author saying things like:

@person for technical accuracy in the X section and @team-docs for content and structure
or
@team please focus extra attention on the new ### Limitations section and the updated screenshots.
or open questions like:
Are there edge cases or user journeys I'm missing? Anything that might confuse readers?

Essentially being more explicit.

I'd vote for de-scoping this PR to do the minimal AI legal compliance thing, and not try to cram general PR hygiene stuff into it TBH

I'd vote for de-scoping this PR to do the minimal AI legal compliance thing, and not try to cram general PR hygiene stuff into it TBH

This is exactly what I'm going to do.

leemthompo · 2025-11-20T09:55:58Z

Few thoughts:

Can we not just bake this into our CLA?
I'm not really sure if there's much point in specifying what model or tool one used, there's AI baked into everything already today and that's trending towards ubiquity
I think we need to distinguish between using AI for syntax versus for semantics, if folks are using an LLM to generate hypothetical technical "facts", or generate code examples, this must be flagged for reviewers. On the other hand, I don't think anybody cares whether you used Gemini 3.1 to make a table out of a list.
@theletterf already drafted AI guidelines, and I think long term the best approach would be to publish those and have a single checkbox on PRs that says "I have read and confirm compliance with the Elastic AI usage policy", we shouldn't try to capture the policy details in a PR template
From hard-won experience, I know how reluctant folks are to fill in PR templates, so keeping additional bureaucracy to a minimum has to be a priority IMO
Ultimately the responsibility falls on the reviewer to verify and quality control any PRs, whether they're generated by a human, an LLM, or a combo.

theletterf · 2025-11-20T10:07:19Z

@theletterf already drafted AI guidelines, and I think long term the best approach would be to publish those and have a single checkbox on PRs that says "I have read and confirm compliance with the Elastic AI usage policy", we shouldn't try to capture the policy details in a PR template

Sadly, we can't still do that, though I'm discussing this internally.

KOTungseth · 2025-11-20T17:26:31Z

Thank you for your feedback, everyone! I agree with Liam's comment to include only the AI disclosure requirements from Legal.

We can add more to this template in the future to meet our team needs.

KOTungseth added 2 commits November 14, 2025 12:24

Adds pull request template

26b1ed7

Changes Contribution checklist to Checklist

16c70be

KOTungseth self-assigned this Nov 14, 2025

KOTungseth requested a review from a team as a code owner November 14, 2025 18:28

KOTungseth added the supportability ability enable self-service or support of product label Nov 14, 2025

KOTungseth requested a review from Copilot November 14, 2025 18:42

Copilot started reviewing on behalf of KOTungseth November 14, 2025 18:42 View session

Copilot finished reviewing on behalf of KOTungseth November 14, 2025 18:43

Copilot AI reviewed Nov 14, 2025

View reviewed changes

KOTungseth marked this pull request as draft November 14, 2025 22:22

Updates summary, checklist, adds reviewers, timeline, and notes

a3358a0

KOTungseth marked this pull request as ready for review November 19, 2025 22:08

bmorelli25 reviewed Nov 20, 2025

View reviewed changes

theletterf approved these changes Nov 20, 2025

View reviewed changes

Removed all sections except summary and AI disclosure questions

a50e60e

KOTungseth merged commit b6e0a3d into elastic:main Nov 20, 2025
7 checks passed

		2. If you answered "Yes" to the previous question, please specify the tool(s) and model(s) used (e.g., Google Gemini, OpenAI ChatGPT-4, etc.).

		Tool(s) and model(s) used:

Adds pull request template #3943

Adds pull request template #3943

Uh oh!

Conversation

KOTungseth commented Nov 14, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

What’s changing

Why this change is needed

What's needed from reviewers

Additional question

Uh oh!

bmorelli25 commented Nov 14, 2025

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Uh oh!

bmorelli25 commented Nov 14, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Top PR Review Issues - Quick Reference

Top Issues by Frequency

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

leemthompo Nov 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

leemthompo commented Nov 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

theletterf commented Nov 20, 2025

Uh oh!

KOTungseth commented Nov 20, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

KOTungseth commented Nov 14, 2025 •

edited

Loading

bmorelli25 commented Nov 14, 2025 •

edited

Loading

leemthompo Nov 20, 2025 •

edited

Loading

leemthompo commented Nov 20, 2025 •

edited

Loading